home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / database / dates501.zip / DATES.DOC < prev    next >
Text File  |  1995-01-07  |  18KB  |  423 lines
  1. DATES.DOC
  2. 01/07/95
  3.  
  4. This program keeps track of birthdays, anniversaries, coming events, etc giving
  5. you advance warning so you can send out cards, leave town, etc.  Features of
  6. this program:
  7.  
  8.   * Initially defaults to showing all events happening within 14 days
  9.   * You can set up multiple date files, each with their own day threshold;
  10.     for example, one file for birthdays, another for business meetings, etc
  11.   * You can establish a different threshold on an event-by-event basis if
  12.     desired.
  13.   * This program can be included in your AUTOEXEC.BAT file to provide notices
  14.     every time you turn on your PC.
  15.   * You can specify dates like the "last Thursday" or the "first Monday" of
  16.     a given month.
  17.   * Vague dates can be entered (e.g. "04/XX/XX Easter") when the exact day
  18.     varies from year to year.
  19.   * Dates can be in the United States format (/DATE=mm/dd/yy) or in most other
  20.     formats (e.g. /DATE=dd-mm-yy).
  21.   * Months can be entered as sequential months (1 for January, 2 for February,
  22.     etc) or else entered as the months themselves (JAN, FEB, etc).
  23.   * Dates don't have to be padded (9/6/94, 09/06/94, and SEP/06/1994 are all
  24.     accepted).
  25.   * The program will show you the weekday, age, and/or days until the event
  26.     if desired.
  27.   * Comment lines can be displayed if desired (e.g. "Events relating to work:")
  28.   * The program can automatically pause when done or after a set number of
  29.     lines if desired.
  30.   * Entries can be sorted before display based on their "date difference" (the
  31.     number of days before the event occurs) or in their original order.
  32.  
  33. The dates file is a simple ASCII text file, created and maintained with any text
  34. editor.  Each record should begin with a date (typically in mm/dd/yy format)
  35. followed by a description of the event.  For example:
  36.  
  37.         05/05/93 Lucy Baines
  38.  
  39. Blank lines or any line which begins with a colon (":") or semi-colon (";") are
  40. ignored by the program.  Lines which begin with an asterisk ("*") are printed
  41. verbatim (minus the asterisk); add spacing after the asterisk if you want the
  42. lines to be indented upon display.  Note:  Comments will be ignored if /SORT
  43. is specified.
  44.  
  45. For the date portion of the record, you have some flexibility.  By default, the
  46. program expects dates to be in a mm/dd/yy format.  So August 5, 1993 is
  47. "08/05/93".
  48.  
  49. You can change the sequence of the numbers by using the "/DATE=format" option.
  50. For example, you can specify "/DATE=dd-mm-yy" if you want.
  51.  
  52.  
  53. Typically, most date formats will use one of the delimiters "-", ".", or "/"
  54. between all various day, month, and year fields.  For example, /DATE=dd.mm.yy
  55. instead of /DATE=dd.mm/dd.  If this is done, your input fields can entered in a
  56. very flexible manner.  The routine will parse the date field based on the
  57. delimiters and accept fields with or without padding, years with or without the
  58. century, and alphabetic months instead of just numeric ones.  For example, using
  59. /DATE=dd.mm.yy, all of the following September 5, 1994 events are the same:
  60.  
  61.         05.09.94 Big event
  62.         5.9.94 Same event
  63.         5.sep.1994 Still the same thing
  64.         05.september.1994 And yet again the same event
  65.  
  66. If you want, you can specify a day of the month based on a relative weekday
  67. within the month.  For example, in the United States, Thanksgiving falls on the
  68. last Thursday in November and Father's Day is the third Sunday in June.
  69.  
  70. If it's a relative weekday from the beginning of the month, DATES allows you to
  71. enter these in the "day" field by using "nww" where "n" indicates the sequence
  72. of the weekday (if you leave it off, it's presumed to be the first) and "ww" is
  73. the first two letters of the day.  If it's a relative weekday from the end of
  74. the month, use "Lnww" ("n" defaults to 1).
  75.  
  76. So, for these two examples, they can be entered in your file as:
  77.  
  78.         11/LTH/XX Thanksgiving
  79.         06/3SU/XX Father's Day
  80.  
  81. The month portion of the date *has* to be filled in.  The day and year portions
  82. can be "xx" if desired.  If a day is "xx", you will be given the notice for the
  83. entire month and for 15 days before the start of the month.  For dates which
  84. vary from year to year and which can't be done using something like "LTH" or
  85. "2MO" (primarily Easter) you can either use the "xx" option for the day or
  86. revise the file every year.
  87.  
  88. Records in the file don't have to be in any particular order.  The dates will be
  89. presented in the order they appear in the file so putting them in chronological
  90. order makes the most sense.
  91.  
  92. There's an initial age threshold for each input dates files.  Thus you could
  93. have a birthday dates file and ask for 14 days warning for each event in it and
  94. have a separate file for important job-related functions that has perhaps a
  95. 30-day warning.  Additionally, you can specify age thresholds on an
  96. event-by-event basis by beginning the relevant descriptions with "/Ddays" (e.g.
  97. "11/01/95 /D60 BIG meeting!").  Specific age thresholds like this are not
  98. overridden by the "/Ddays" parameter specified from the command line.
  99.  
  100.  
  101. In addition to being able to specify "/Ddays" on an event-by-event basis,
  102. certain command-line parameters can be imbedded within the dates input file.
  103. See the discussion about "Syntax" later for a description of these parameters.
  104. These parameters must begin in the first column of the line and only one
  105. parameter can be specified on a line.  These parameters override one or more
  106. defaults for the current input file only and can be set and reset throughout the
  107. file.  The acceptable parameters are:
  108.  
  109.         /Ddays                   (can also be specified for an individual event)
  110.         /DATE=format
  111.         /DATE   and /-DATE
  112.         /DAY    and /-DAY        (same as /WEEKDAY and /-WEEKDAY)
  113.         /AGE    and /-AGE
  114.         /CTDOWN and /-CTDOWN
  115.         /COLOR=nnn nnn nnn nnn
  116.  
  117. For example:
  118.  
  119.         01/01/XX A stellar new years event
  120.         /-AGE
  121.         /-DAY
  122.         01/20/92 Expect the unexpected!
  123.         01/22/94 Another one (still covered by same parameters)
  124.         /AGE
  125.         01/23/94 Skipping age on this one
  126.         /-AGE
  127.         01/25/94 And reinstating it here
  128.  
  129. A sample United States-oriented DATES.TXT file is provided and consists of the
  130. following lines:
  131.  
  132.         01/01/xx New Year's Day
  133.         01/3MO/xx Martin Luther King's birthday
  134.         02/14/xx Valentine's Day
  135.         03/17/xx St. Patrick's Day
  136.         03/30/xx -ish Easter
  137.         04/07/xx -ish Daylight Savings Time begins
  138.         05/2SU/xx Mother's Day
  139.         05/LMO/xx Memorial Day
  140.         05/31/57 Bruce Guthrie
  141.         07/04/xx July 4th
  142.         09/1MO/xx Labor Day
  143.         10/27/xx -ish Daylight Savings Time ends
  144.         10/31/xx Halloween
  145.         11/11/xx Veteran's Day
  146.         11/4TH/xx Thanksgiving
  147.         12/25/xx Christmas
  148.  
  149. As far as the actual display of the information is concerned, each event is
  150. typically presented as just "date event", where any relative day references like
  151. "4TH" get resolved before the date is shown.  For example, presume it's May 25
  152. in 1994, /D14 is in effect, and your input file has the following three lines:
  153.  
  154.         05/28/30 Mr.Fury
  155.         05/LMO/xx Memorial Day
  156.         05/31/57 Bruce Guthrie
  157.  
  158.  
  159. The initial display settings are /DATE /-DAY /-AGE /-CTDOWN.  This presents the
  160. information as:
  161.  
  162.         05/28/30 Mr.Fury
  163.         05/30/xx Memorial Day
  164.         05/31/57 Bruce Guthrie
  165.  
  166. See the syntax descriptions for what each of these settings mean.  Changing the
  167. settings to /-DATE /DAY /AGE /CTDOWN presents it as:
  168.  
  169.         [Sat] (64th) 3 days until Mr.Fury
  170.         [Mon] 5 days until Memorial Day
  171.         [Tue] (37th) 6 days until Bruce Guthrie
  172.  
  173.  
  174. Multiple input files with different date restrictions:
  175.  
  176. You can specify multiple date input files.  They are processed in the order
  177. they are entered.  By default, each will have the initial date restriction
  178. (typically 14 days).  You can override the date restriction for a specific file
  179. by including the date restriction after the file name.  For example:
  180.  
  181.         DATES DATE1.TXT DATE2.TXT /D10 DATE3.TXT
  182.  
  183. Given a default 14-day restriction, the date restrictions will be 14 days for
  184. DATE1.TXT and DATE3.TXT, 10 days for DATE2.TXT.  If you want to override the
  185. date restriction for all files, include that date restriction before the file
  186. name.  For example:
  187.  
  188.         DATES /D5 DATE1.TXT DATE2.TXT /D10 DATE3.TXT
  189.  
  190. In this case, the date restriction will be 5 days for DATE1.TXT and DATE3.TXT
  191. and 10 days for DATE2.TXT.
  192.  
  193.  
  194.  
  195. Specifying parameters:
  196.  
  197. Parameters for this program can be set in the following ways.  The last setting
  198. encountered always wins:
  199.   - Read from an *.INI file (see below),
  200.   - Through the use of an environmental variable (SET DATES=whatever), or
  201.   - From the command line (see "Syntax" below)
  202.  
  203.  
  204. The DATES.INI file:
  205.  
  206. DATES will read a DATES.INI file if one is found.  (You can specify a different
  207. file name if desired.) The file is an ASCII text file that can be created
  208. maintained by hand.  The file can consist or one or more command line
  209. parameters (only those that begin with a "/"; no multi-word ones), one statement
  210. per line.
  211.  
  212. The file can also contain comments which are blank lines or any line beginning
  213. with:
  214.         ;    (semi-colon)
  215.         :    (colon)
  216.         '    (quote)
  217.  
  218. DATES looks for the initialization file in your default subdirectory first.  It
  219. then searches for it in the subdirectory where the executable was and then goes
  220. through your DOS path.
  221.  
  222. Passing in "/-I" or "/INULL" skips loading the INI file.  This saves some
  223. execution time as the program does not need to search your path for the file.
  224.  
  225.  
  226.  
  227. Syntax:
  228.  
  229.     DATES [ date_file [...] ] [ /Ddays ] [ /SKIP | /-SKIP ] [ /DATE=format ]
  230.       [ /DATE | /-DATE ] [ /DAY | /-DAY ] [ /AGE | /-AGE ] [ /CTDOWN | /-CTDOWN ]
  231.       [ /COLOR=nnn nnn nnn ] [ /MONO | /COLOR ] [ /Q | /-Q ] [ /SORT | /-SORT ]
  232.       [ /GLOBAL | /-GLOBAL ] [ /CLS | /-CLS ] [ /P | /Pn | /-P ]
  233.       [ /W | /W0 | /-W ] [ /R ] [ /Iinitfile | /-I ] [ /? ] [ > filename ]
  234.  
  235. where:
  236.  
  237. "date_file" is the name of the input text file.  It can contain drive and path
  238. information if desired.  This defaults to DATES.TXT.  If no filename is
  239. specified, the program will check for it along your DOS path beginning with your
  240. default subdirectory.  Multiple date files and date restrictions are allowed.
  241. See the notes above about this.
  242.  
  243. "/Ddays" (or "days") are the number of days in advance you want the warning.
  244. Initially defaults to /D14.  Generic days ("11/xx/xx") are not affected by this
  245. setting; you automatically get the notice 15 days before the beginning of the
  246. month and through the entire month itself.  Events coded with specific "/Ddays"
  247. entries are also not affected by the command-line "/Ddays" setting.
  248.  
  249. "/SKIP" says to print a message (unless /Q is specified) but otherwise ignore
  250. it if one or more of the date input files is not found.
  251.  
  252. "/-SKIP" says to abort if any of the input files are not found.
  253.  
  254. "/DATE=format" specifies the format that the date is to have.  The date must
  255. consist of pairs of "mm" (month), "dd" (day), and "yy" (year) characters in any
  256. order.  If a delimiter is used between the pairs, it can be any non-space
  257. character (like "-" or "/").  If your delimiter is the same between the three
  258. sets of date portions (e.g.  /DATE=mm/dd/yy or /DATE=dd.mm.yy), you have a
  259. considerable amount of flexibility in terms of what sort of entries can appear.
  260. See the notes at the beginning of this documentation.  Initially defaults to
  261. "/DATE=mm/dd/yy".
  262.  
  263. "/DATE" indicates that the date is to be presented if the entry is show.
  264. This is initially the default.
  265.  
  266. "/-DATE" skips showing the date of the event when it's displayed.
  267.  
  268. "/DAY" (or "/WEEKDAY") shows the day of the week for each event if possible.
  269.  
  270. "/-DAY" (or "/-WEEKDAY") skips showing the day of the week.  This is initially
  271. the default.
  272.  
  273. "/AGE" shows the age of the event when it's displayed.  This is only done for
  274. entries that have a specific year.  This is initially the default.
  275.  
  276. "/-AGE" skips showing the age of the event.
  277.  
  278. "/CTDOWN" adds a "x days until" message in front of any displayed event.
  279.  
  280. "/-CTDOWN" skips adding the "x days until" message.  This is initially the
  281. default.
  282.  
  283.  
  284. "/COLOR=nnn nnn nnn" specifies the color settings to use for (in order) regular
  285. text, dates happening today, and the ages of dates happening today.  Any input
  286. lines which begin with an asterisk are printed using the third color set.  Each
  287. setting must consist of three digits, the first two being the foreground color
  288. and the last being the background color.  The foreground color should be padded
  289. on the left with a 0 if it is only one digit in length.  Defaults to "COLOR=070
  290. 150 090".
  291.  
  292. Foreground colors:
  293.  
  294.         Low intensity           High intensity
  295.  
  296.         0 = black                8 = dark grey
  297.         1 = blue                 9 = light blue
  298.         2 = green               10 = light green
  299.         3 = cyan                11 = light cyan
  300.         4 = red                 12 = light red
  301.         5 = magenta             13 = light magenta
  302.         6 = brown               14 = light yellow
  303.         7 = white               15 = bright white
  304.  
  305. Adding 16 to any color will make the text blink.  Background colors can consist
  306. of 0 to 7 above.  Bright white on blue, for example, would be "151".
  307.  
  308. "/MONO" suppresses all screen color settings.
  309.  
  310. "/COLOR" allows screen color settings and is initially the default.
  311.  
  312. "/Q" stops the printing every message except for the actual date lines.  This
  313. option is automatically invoked if redirection is used.
  314.  
  315. "/-Q" turns back on the printing of almost every message.  This is the initially
  316. default unless redirection is used.
  317.  
  318. "/SORT" sorts the entries by their date difference (the number of days between
  319. now and the date of the event).  If you're using more than one dates file with
  320. the "/-GLOBAL" (default) parameter, all appropriate entries from a given dates
  321. file will be sorted and displayed before any entries from the next dates file
  322. are displayed.  The "/GLOBAL" parameter will combine them all before sorting
  323. them.  Using "/SORT" precludes you from showing any display comments (lines
  324. beginning with "*") in your file.  Currently, the program limits you to
  325. displaying 100 items per input file if /SORT is specified; let me know if this
  326. limit is too low for you.
  327.  
  328. "/-SORT" says to display the entries as they're found in the files.  This is
  329. initially the default.
  330.  
  331. "/GLOBAL" invokes "/SORT" and merges multiple date input files if found, sorting
  332. them as a unit instead of individually.
  333.  
  334. "/-GLOBAL" treats each date input file as a unique entity for sorting purposes.
  335. This is initially the default.
  336.  
  337. "/CLS" clears the display before showing the results.
  338.  
  339. "/-CLS" does not clear the display first.  This is the default.
  340.  
  341.  
  342. "/P" says to pause the output every 23 lines.  (NOTE:  The /P, /Pn, and /-P
  343. options affect pausing while listing events; the /W, /W0, /-W options affect
  344. pausing after the program finishes.)
  345.  
  346. "/Pn" says to pause the output every n-number of lines.
  347.  
  348. "/-P" says to not pause the output at all.  This is initially the default.
  349.  
  350. "/W" says to pause with a "Press any key to continue" message after the
  351. program finishes if any hits were found.
  352.  
  353. "/W0" says to pause afterward whether any hits were found or not.
  354.  
  355. "/-W" says to not pause afterward at all.  This is initially the default.
  356.  
  357. "/R" sets a DOS return code equal to the number of dates found.  The standard
  358. way to use something like this is with a test on the DOS ERRORLEVEL in an
  359. AUTOEXEC.BAT file or something.  For example:
  360.  
  361.        DATES /R
  362.        IF ERRORLEVEL 1 GOTO HITS
  363.        GOTO END
  364.        :HITS
  365.        PAUSE
  366.        :END
  367.        ECHO DONE
  368.  
  369. Note that the results of particular example could have been done easier using
  370. DATES' /W parameter.
  371.  
  372. "/Iinitfile" says to read an initialization file with the file name "initfile".
  373. The file specification *must* contain a period.  If no drive or path information
  374. is specified, the program will search for initfile beginning in your default
  375. subdirectory and then going throughout your DOS path.  The use of an
  376. initialization file is optional.  Initially defaults to "/IDATES.INI".
  377.  
  378. "/-I" (or "/INULL") says to skip loading the initialization file.
  379.  
  380. "/?" or "/HELP" or "HELP" shows you the syntax for the command.
  381.  
  382. "> filename" redirects the output to a DOS file.  This is standard DOS
  383. redirection.  Automatically invokes /Q option and turns off the last of the
  384. status messages.
  385.  
  386.  
  387. Return codes:
  388.  
  389. DATES returns the following ERRORLEVEL codes:
  390.       255 = syntax problems, or /? requested
  391.  
  392. If /R is specified, the ERRORLEVEL code will be the number of hits found.
  393.  
  394.  
  395.  
  396. Author:
  397.  
  398. This program was written by Bruce Guthrie of Wayne Software.  It is free for use
  399. and redistribution provided relevant documentation is kept with the program, no
  400. changes are made to the program or documentation, and it is not bundled with
  401. commercial programs or charged for separately.  People who need to bundle it in
  402. for-sale packages must pay a $50 registration fee to "Wayne Software" at the
  403. following address.
  404.  
  405. Additional information about this and other Wayne Software programs can be found
  406. in the file BRUCEymm.DOC which should be included in the original ZIP file.
  407. ("ymm" is replaced by the last digit of the year and the two digit month of the
  408. release.  BRUCE312.DOC came out in December 1993.  This same naming convention
  409. is used in naming the ZIP file that this program was included in.) Comments and
  410. suggestions can also be sent to:
  411.  
  412.                 Bruce Guthrie
  413.                 Wayne Software
  414.                 113 Sheffield St.
  415.                 Silver Spring, MD 20910
  416.  
  417.                 fax: (301) 588-8986
  418.  
  419. See BRUCEymm.DOC file for additional contact information.
  420.  
  421. Foreign users:  Please provide an Internet e-mail address in all correspondence.
  422.  
  423.